Station Headless Proposal v0

Proposed project name: Station Server

Let operators run Station in headless mode, on servers and other machines that don’t have a graphical environment. This grows the Station ecosystem:

  • Station in data centers, with fast connections
  • Stations on always-on hardware
  • Stations on beefy hardware

Features

  • CLI
    🟢 Required (It’s a core Station Server feature)
    • npm install -g station-server
    • station
    • station --help
    • station wallet --balance
    • station activities
  • Storage
    🟢 Required (It’s a core Station feature)
    • Pick folder on disk $STATION_ROOT = ~/.station/
    • (Re-)create folder structure on launch
    • Store event streams of various kinds (module logs, wallet transactions, etc.) in individual log files
    • Truncate log files to 10MB each max
  • HTTP interface
    🟡 Optional: Aside being a potentially nicer interface than direct access to log files, Station Desktop can connect to Station Server through this over the network. The file interface is limited to same machine access. We could then turn Station Desktop into a light client for this HTTP interface. By default, Station Desktop would bundle and connect to its own instance of Station Server.
    • GET /logs/modules/:name
    • GET /logs/modules/:name?err
    • GET /metrics
    • GET /wallet/address
    • GET /wallet/balance
    • GET /wallet/transactions
    • POST /wallet/transfer/:destination
    • Authentication
      • SSH tunnel?
      • JWT?
    • Default port: 3266
  • Process management
    🟢 Required (It’s a core Station feature)
    • Launch module process
    • Restart module process
    • Pass module data folder
      ROOT_DIR=$STATION_ROOT/modules/${MODULE_NAME}
    • Pass wallet address
      FIL_WALLET_ADDRESS=f1...
    • Store module stdout
      • File: $STATION_ROOT/logs/modules/${MODULE_NAME}.log
      • Example: 2023-02-16T22:59:47.385+0100 INFO: Saturn Node is online and connected to 9 peers
    • Store module stderr
      • File: $STATION_ROOT/logs/modules/${MODULE_NAME}.err.log
      • Example: 2023-02-16T22:59:47.385+0100 Dang!
  • Auto-update
    🟢 Required (It’s a core Station feature)
    • How to auto-update on Linux?
    • One way would be to mirror Saturn’s Docker + Watchtower setup
    • Will Docker be available on all hosts? On tiny devices it might not make sense
    • Alternatively, have update.sh script, and add to crontab, just like initial Saturn
    • Depends on the runtime used. If Node.js, can use combination of pm2 and npm install ...
  • Trusted Modules
    🟢 Required (It’s a core Station feature)
    • Bundle Saturn L2 Node
  • Metrics
    🟢 Required (It’s a core Module feature)
    • Collect module metrics (totalJobsCompleted)
    • Write metrics updates to disk
      • File: $STATION_ROOT/logs/metrics.log
      • Example: 2023-02-16T22:59:47.385+0100 {"totalJobsCompleted":123}
  • Wallet
    ❓ What is the safest architecture? Who owns the private key, are we able to offer safe remote access to a wallet? Or should Station Desktop (the client) own the wallet?
    • Create/read/store seed phrase
    • Get wallet address from API
    • Pass to module via ENV var
    • Periodically fetch and print new transactions
      • File: $STATION_ROOT/logs/wallet/transactions.log
      • Example: 2023-02-16T22:59:47.385+0100 {"from":"...","amount":"..."}
    • Periodically fetch and print updated balance
      • File: $STATION_ROOT/logs/wallet/balance.log
      • Example: 2023-02-16T22:59:47.385+0100 100
    • Provide command for transferring funds
      $ station transfer $DESTINATION_ADDRESS
    • Authentication
      • MetaMask?
  • Activity logs
    🟡 Optional (All information is found in process management logs, just needs to be parsed)
    • Aggregate high-level logs
      • File: $STATION_ROOT/logs/activity.log
      • Example: 2023-02-16T22:59:47.385+0100 Saturn Node is online and connected to 9 peers
      • File: $STATION_ROOT/logs/activity.err.log
      • Example: 2023-02-16T22:59:47.385+0100 Saturn Node is not able to connect to the network
  • Auto-start
    🟡 Optional: Operators can maintain auto-start however they wish, and are expected to be capable of doing so

Example

# Install Station (which name to pick?)
$ npm install -g station-server
$ npm install -g filecoin-station-server

# Launch Station
$ station
...

# Transfer out funds (if Wallet)
$ station transfer $DESTINATION_ADDRESS
...

# Configuration
$ export STATION_ROOT=~/.station/ # (default)
$ export STATION_FIL_WALLET_ADDRESS=f1... # (if not wallet)

# Get latest metrics
$ station metrics
totalJobsCompleted=123

# Or:
$ tail -n1 $STATION_ROOT/logs/metrics.log
2023-02-16T22:59:47.385+0100 {"totalJobsCompleted":123}

# Or:
$ curl http://localhost:3266/metrics

# List module logs
$ station logs saturn-l2-node

# Or:
$ tail -f $STATION_ROOT/logs/modules/saturn-l2-node{,.err}.log
==> $STATION_ROOT/logs/modules/saturn-l2-node.log <==
2023-02-16T22:59:47.385+0100 INFO: Saturn Node is online and connected to 9 peers
2023-02-16T22:59:47.385+0100 ERROR: Saturn Node is not able to connect to the network

==> $STATION_ROOT/logs/modules/saturn-l2-node.err.log <==
2023-02-16T22:59:47.385+0100 Dang!

# Or:
$ curl http://localhost:3266/logs/modules/saturn-l2-node{,?err}

# Get wallet balance (optional)
$ station wallet balance
100

# Or:
$ tail -n1 $STATION_ROOT/logs/wallet/balance.log
2023-02-16T22:59:47.385+0100 100

# Or:
$ curl http://localhost:3266/wallet/balance

# List wallet history (optional)
$ station wallet transactions
from=...

# Or:
$ tail -f $STATION_ROOT/logs/wallet/transactions.log
2023-02-16T22:59:47.385+0100 {"from":"...","amount":"..."}
2023-02-16T22:59:47.385+0100 {"from":"...","amount":"..."}
2023-02-16T22:59:47.385+0100 {"from":"...","amount":"..."}

# Or:
$ curl http://localhost:3266/wallet/transactions

# List activity log (optional)
$ station activity

# Or:
$ tail -f $STATION_ROOT/logs/activity{,.err}.log
==> $STATION_ROOT/logs/activity.log <==
2023-02-16T22:59:47.385+0100 Saturn Node is online and connected to 9 peers
2023-02-16T22:59:47.385+0100 Saturn Node is online and connected to 7 peers

==> $STATION_ROOT/logs/activity.err.log <==
2023-02-16T22:59:47.385+0100 Saturn Node is not able to connect to the network

# Or:
$ curl http://localhost:3266/logs/activity{,?err}

Machine requirements

  • As a standalone product, don’t support Windows or Mac as first class citizens
    • They will always have GUI → Use Station desktop app
  • Don’t support Windows or Mac server
    • They are niche products
  • Support Linux
    • How to install?
      • npm install -g station-server
      • curl script
      • ansible script
    • Dependencies
      • Debian/Ubuntu: sudo apt-get install libsecret-1-dev
      • Red Hat-based: sudo yum install libsecret-devel
      • Arch Linux: sudo pacman -S libsecret
  • Runtime
    • If we use Node.js, we can re-use most Station code. However: Operators need to have nodejs installed
    • If we use rust or go, we need to rewrite everything, but don’t need nodejs
    • Suggestion: Use Node.js, for speed of delivery

Name

From Juan:

  • maybe call it "server-station" so that people know where it is meant to be deployed?
  • (although i guess in theory this could be deployed to desktops too... hm maybe gui-station and headless-station is right)
  • “Headless” gives the impression that this is just a GUI ported for headless environments

Suggestion:

  • Keep “Station” name for desktop version, or call it “Station Desktop”. The name shouldn’t be technical, since it’s an accessible desktop application
  • Headless Station name suggestions:
    • Station
    • Station Server
    • Station CLI
    • Station Core
  • Desktop name suggestions:
    • Station Desktop
    • Station
    • Station Viewer
    • Station Panel
  • Examples
    • Docker & Docker Desktop
    • Git & Git Viewer
    • Station & Station Desktop (or Station Client)

Implementation

Station Desktop as light client

Move the cover business logic into Station Server, and turning Station Desktop into a consumer of Station Server

Station Server as backend of Station Desktop

Station Server can serve as backend for Station Desktop, and as its own product, for headless Station use-cases. This way the core business logic lives in Station (Server), and can be written in any language. Station Server will be decoupled from the UI, at the cost of having to update more projects in order to ship features or other updates.

This way other people can even create their own UI on top if they wish.

Roadmap

  1. Prototype of the architecture / Figure out a version 0.1
  1. CLI (All 🟢 but no HTTP)
  1. Add HTTP
  1. Connect Station Desktop to Server

❓ items

  1. Add wallet

User groups

  • User uses only Station Server
  • User uses Station Server in conjunction with Station Desktop